Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

BeginMediaEdits

The BeginMediaEdits function starts a media-editing session.

pascal OSErr BeginMediaEdits (Media theMedia);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

EndMediaEdits

The EndMediaEdits function ends a media-editing session.

pascal OSErr EndMediaEdits (Media theMedia);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

AddMediaSample

The AddMediaSample function adds sample data and a description to a media. Your application specifies the sample and the media for the operation. The AddMediaSample function updates the media so that it contains the sample data. One call to this function can add several samples to a media--however, all the samples must be the same size. Samples are always appended to the end of the media. Furthermore, each time a sample is added, the media duration is extended.

pascal OSErr AddMediaSample (Media theMedia, Handle dataIn,
                                         long inOffset, unsigned long size,
                                         TimeValue durationPerSample,
                                         SampleDescriptionHandle sampleDescriptionH,
                                         long numberOfSamples, short sampleFlags,
                                         TimeValue *sampleTime);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

dataIn

Contains a handle to the sample data. The AddMediaSample function adds this data to the media specified by the parameter theMedia . You specify the number of bytes of sample data with the size parameter. You can use the inOffset parameter to specify a byte offset into the data referred to by this handle.

inOffset

Specifies an offset into the data referred to by the handle contained in the dataIn parameter. Set this parameter to 0 if there is no offset.

size

Specifies the number of bytes of sample data to be added to the media. This parameter indicates the total number of bytes in the sample data to be added to the media, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the sample data.

durationPerSample

Specifies the duration of each sample to be added. You must specify this parameter in the media's time scale. For example, if you are adding sound that was sampled at 22 kHz to a media that contains a sound track with the same time scale, you would set the durationPerSample parameter to 1. Similarly, if you are adding video that was recorded at 10 frames per second to a video media that has a time scale of 600, you would set this parameter to 60 to add a single sample.

sampleDescriptionH

Contains a handle to a sample description. Some media structures may require sample descriptions. There are different sample descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an image description (see the chapter "Image Compression Manager" in this book for more information about image description structures). A media that contains sound requires that you supply a sound description structure (see "The Sound Description Structure" for more information about sound description structures).

If the media does not require a sample description, set this parameter to nil .

numberOfSamples

Specifies the number of samples contained in the sample data to be added to the media.

This parameter determines the size of each sample. The Movie Toolbox considers the value of this parameter as well as the value of the size parameter when it determines the size of each sample that it adds to the media. You should set the value of this parameter so that the resulting sample size represents a reasonable compromise between total data retrieval time and the overhead associated with input and output (I/O). You should also consider the speed of the data storage device--CD-ROM devices are much slower than hard disks, for example, and should therefore have a smaller sample size.

For a video media, set a sample size that corresponds to the size of a frame. For a sound media, choose a number of samples that corresponds to between 0.5 and 1.0 seconds of sound. In general, you should not create groups of sound samples that are less than 2 KB in size or greater than 15 KB. Typically, a sample size of about 8 KB is reasonable for most storage devices.

sampleFlags

Contains flags that control the add operation. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

sampleTime

Contains a pointer to a time value. After adding the sample data to the media, the AddMediaSample function returns the time where the sample was inserted in the time value referred to by this parameter. If you do not want to receive this information, set this parameter to nil .

AddMediaSampleReference

The AddMediaSampleReference function allows your application to work with samples that have already been added to a movie data file. Instead of actually writing out samples to disk, this function writes out references to existing samples, which you specify in the dataOffset and size parameters.

pascal OSErr AddMediaSampleReference (Media theMedia,
                                         long dataOffset,
                                         unsigned long size,
                                         TimeValue durationPerSample,
                                         SampleDescriptionHandle sampleDescriptionH,
                                         long numberOfSamples, short sampleFlags,
                                         TimeValue *sampleTime);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

dataOffset

Specifies the offset into the movie data file. This parameter is used differently by each data handler. For example, for the standard HFS data handler, this parameter specifies the offset into the file. This parameter contains either data you add yourself or the data offset returned by the GetMediaSampleReference function (described on GetMediaSampleReference ).

size

Specifies the number of bytes of sample data to be identified by the reference. This parameter indicates the total number of bytes in the sample data, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the reference.

durationPerSample

Specifies the duration of each sample in the reference. You must specify this parameter in the media's time scale. For example, if you are referring to sound that was sampled at 22 kHz in a media that contains a sound track with the same time scale, to add a reference to a single sample you would set the durationPerSample parameter to 1. Similarly, if you are referring to video that was recorded at 10 frames per second in a video media that has a time scale of 60, you would set this parameter to 6 to add a reference to a single sample.

sampleDescriptionH

Contains a handle to a sample description. Some media structures may require sample descriptions. There are different sample descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an image description (see the chapter "Image Compression Manager" in this book for more information about image description structures). A media that contains sound requires that you supply a sound description structure (see "The Sound Description Structure" for more information about sound description structures).

If the media does not require a sample description, set this parameter to nil .

numberOfSamples

Specifies the number of samples contained in the reference. For details, see the AddMediaSample function description beginning on AddMediaSample .

sampleFlags

Contains flags that control the operation. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

sampleTime

Contains a pointer to a time value. After adding the reference to the media, the AddMediaSampleReference function returns the time where the reference was inserted in the time value referred to by this parameter. If you do not want to receive this information, set this parameter to nil .

GetMediaSample

The GetMediaSample function returns a sample from a movie data file. You add samples to movie data files with the AddMediaSample function (described on AddMediaSample ).

pascal OSErr GetMediaSample (Media theMedia, Handle dataOut,
                                         long maxSizeToGrow, long *size,
                                         TimeValue time, TimeValue *sampleTime,
                                         TimeValue *durationPerSample,
                                         SampleDescriptionHandle sampleDescriptionH,
                                         long *sampleDescriptionIndex,
                                         long maxNumberOfSamples,
                                         long *numberOfSamples,
                                         short *sampleFlags);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

dataOut

Contains a handle. The GetMediaSample function returns the sample data into this handle. The function increases the size of this handle, if necessary. You can specify the handle's maximum size with the maxSizeToGrow parameter.

maxSizeToGrow

Specifies the maximum number of bytes of sample data to be returned. The GetMediaSample function does not increase the handle specified by the dataOut parameter to a size greater than you specify with this parameter. Set this value to 0 to enforce no limit on the number of bytes to be returned.

size

Contains a pointer to a long integer. The GetMediaSample function updates the field referred to by the size parameter with the number of bytes of sample data returned in the handle specified by the dataOut parameter. Set this parameter to nil if you are not interested in this information.

time

Specifies the starting time of the sample to be retrieved. You must specify this value in the media's time scale.

sampleTime

Contains a pointer to a time value. The GetMediaSample function updates this time value to indicate the actual time of the returned sample data. If you are not interested in this information, set this parameter to nil .

The returned time may differ from the time you specified with the time parameter. This will occur if the time you specified falls in the middle of a sample.

durationPerSample

Contains a pointer to a time value. The Movie Toolbox returns the duration of each sample in the media. This time value is expressed in the media's time scale. Set this parameter to 0 if you do not want this information.

sampleDescriptionH

Contains a handle to a sample description. The GetMediaSample function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you do not want the sample description, set this parameter to nil .

sampleDescriptionIndex

Contains a pointer to a long integer. The GetMediaSample function returns an index value to the sample description that corresponds to the returned sample data. If you do not want this information, set this parameter to nil .

You can use this index to retrieve the sample description by calling the GetMediaSampleDescription function, which is described on GetMediaSampleDescription .

You can retrieve the sample description itself by using the sampleDescriptionH parameter.

maxNumberOfSamples

Specifies the maximum number of samples to be returned. The Movie Toolbox does not return more samples than you specify with this parameter.

If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media, and returns that value in the field referenced by the numberOfSamples parameter.

numberOfSamples

Contains a pointer to a long integer. The GetMediaSample function updates the field referred to by this parameter with the number of samples it actually returns. If you do not want this information, set this parameter to nil .

sampleFlags

Contains a pointer to a short integer. The GetMediaSample function returns flags that describe the sample. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample that is returned is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

If you do not want this information, set this parameter to nil .

GetMediaSampleReference

The GetMediaSampleReference function allows your application to obtain reference information about samples that are stored in a movie data file.

pascal OSErr GetMediaSampleReference (Media theMedia,
                                         long *dataOffset,long *size, TimeValue time,
                                         TimeValue *sampleTime,
                                         TimeValue *durationPerSample,
                                         SampleDescriptionHandle sampleDescriptionH,
                                         long *sampleDescriptionIndex,
                                         long maxNumberOfSamples,
                                         long *numberOfSamples, short *sampleFlags);


theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

dataOffset

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by this parameter with the offset to the sample data.

This parameter is used differently by each media handler. For example, the hierarchical file system (HFS) media handler returns an offset into the file that contains the media data.

size

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by the size parameter with the number of bytes of sample data referred to by the reference. Set this parameter to nil if you are not interested in this information.

time

Specifies the starting time of the sample reference to be retrieved. You must specify this value in the media's time scale.

sampleTime

Contains a pointer to a time value. The GetMediaSampleReference function updates this time value to indicate the actual time of the returned sample data. If you are not interested in this information, set this parameter to nil .

The returned time may differ from the time you specified with the time parameter. This will occur if the time you specified falls in the middle of a sample.

durationPerSample

Contains a pointer to a time value. The Movie Toolbox returns the duration of each sample in the media. This time value is expressed in the media's time scale. Set this parameter to 0 if you do not want this information.

sampleDescriptionH

Contains a handle to a sample description. The GetMediaSampleReference function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you do not want the sample description, set this parameter to nil .

sampleDescriptionIndex

Contains a pointer to a long integer. The GetMediaSampleReference function returns an index value to the sample description that corresponds to the returned sample data. You can use this index to retrieve the media sample description with the GetMediaSampleDescription function, which is described on GetMediaSampleDescription . If you do not want this information, set this parameter to nil .

You can retrieve the sample description itself by using the sampleDescriptionH parameter.

maxNumberOfSamples

Specifies the maximum number of samples to be returned. The Movie Toolbox does not return a reference that refers to more samples than you specify with this parameter.

If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media and returns that value in the field referenced by the numberOfSamples parameter.

numberOfSamples

Contains a pointer to a long integer. The GetMediaSampleReference function updates the field referred to by this parameter with the number of samples referred to by the returned reference. If you do not want this information, set this parameter to nil .

sampleFlags

Contains a pointer to a short integer. The GetMediaSampleReference function returns flags that describe the samples referred to by the reference. The following flag is available (unused flags are set to 0):

mediaSampleNotSync

Indicates the sample that is returned is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

If you do not want this information, set this parameter to nil .